Writing Telephone Tools (IM: Telephony)

Inside Macintosh: Telephony /: Chapter 6 - Telephone Tools

Writing Telephone Tools
Because the Telephone Manager is part of the Communications Toolbox, a telephone tool is a collection of six resources. These resource include a bundle resource (of type vbndType) that contains the name of the tool and information about the other resources that belong to the tool. The remaining five resources are code resources that handle specific operations:

The vdefType resource is the main code resource. It handles messages related to general telephony functions (such as TELNew).
The vvalType resource is the validation code resource. It validates telephone records (when an application calls TELValidate) and also fills in configuration record default values (when an application calls TELDefault).
The vsetType resource is the setup-definition code resource. It supports operations involving a custom dialog box that allows users to configure the telephone tool.
The vscrType resource is the scripting language interface code resource. It handles the communication between a scripting language and the telephone tool.
The vlocType resource is the localization code resource. It handles the localization of configuration strings related to the telephone tool.

IMPORTANT
The bundle resource is optional in a telephone tool, but all five code resources are required.
The following six sections describe in detail how to construct these six resources. The section "Sending Messages to the Telephone Manager," beginning on page 6-9 explains how to send messages to the Telephone Manager.

Constructing a Bundle Resource
A telephone tool's bundle resource contains a list of the resources that are associated with the tool. The bundle resource can contain references to the five standard code resources and to any additional resources that your tool might need, such as dialog boxes or menus.
A bundle resource is optional. The Telephone Manager can load and manage your tool even if it lacks a bundle resource, but it's a good idea to include one in your tool. The bundle resource allows you to change resource IDs when conflicts arise, without having to recompile your code. Your telephone tool can refer to resources with local IDs that the Communications Resource Manager can map to actual resource IDs. (Your tool should use the Communications Resource Manager routines CRMLocalToRealID and CRMRealToLocalID.) Listing 6-1 shows the Rez template of a bundle resource.
Listing 6-1 Rez template of a bundle resource
type 'vbnd' {
   integer = $$CountOf(TypeArray)- 1;
   array TypeArray {
      literal longint;     /*type*/
      integer = $$CountOf(IDArray) - 1;
      wide array IDArray {
         integer;          /*local ID*/
         integer;          /*actual ID*/
      };
   };
};
Writing a Main Code Resource
The main code resource of your tool serves two purposes. The first is to receive and handle messages from the Telephone Manager. These messages relate to general telephony operations, such as originating an outgoing telephone call or answering an incoming telephone call. The second purpose is to send messages to the master message handlers of the Telephone Manager, in response to activity on the telephone network.

Note
See "Sending Messages to the Telephone Manager" on page 6-9 for information on sending messages from your tool to the Telephone Manager.
A main code resource is of type vdefType. The entry point of the resource should be a function declared as follows:
pascal short MyVDEF (
                     TELHandle hTEL, 
                     TELTermPtr pTELTerm, 
                     TELDNHandle hDN, 
                     TELCAHandle hCA, 
                     short msg, 
                     long p1, 
                     long p2, 
                     long p3);
The msg parameter contains a constant that specifies the message being sent. The other parameters contain information necessary for your tool to interpret and respond to that message. For example, if msg contains the constant telCountDNsMsg, then the parameter p1 specifies the types of directory numbers to count, and parameter p2 is a Boolean value that specifies whether to count all directory numbers (true) or only those to which commands can be sent (false). Parameters hDN, hCA, and p3 are unused for the telCountDNsMsg message.
Listing 6-2 illustrates a part of a sample main code resource.
Listing 6-2 The entry point of a main code resource
pascal short MyVDEF (TELHandle hTEL, TELTermPtr pTELTerm, TELDNHandle hDN, 
               TELCAHandle hCA, short msg, long p1, long p2, long p3)
{
   short myResult;

   switch (msg) {
      telNewMsg:
         myResult = MyHandleTelNewMsg(hTEL, pTELTerm, p1);
         break;
      telDisposeMsg:
         myResult = MyHandleTelDisposeMsg(hTEL, pTELTerm);
         break;

      //handle other messages here

      default:
         myResult = -1;
         break;
   }

   return(myResult);
}
See "Main Code Resource Messages," beginning on page 6-11 for a complete description of the messages your main code resource should be prepared to handle.

Writing a Validation Code Resource
A validation code resource validates telephone records and fills in configuration record default values. The entry point of the resource should be a function declared as follows:
pascal long MyVVAL (TELHandle hTEL, short msg, long p1, long p2, long p3);
When this function is called, the msg parameter contains one of two messages, defined by constants:
enum {
   telL2EnglishMsg         = 0,
   telL2IntlMsg            = 1
};
These messages indicate that your tool should localize a string either to English or to some other language. The parameters p1, p2, and p3 have different meanings depending on which message is passed in the msg parameter. See "Validation Code Resource Messages" on page 6-40 for complete details.

Writing a Setup-Definition Code Resource
A setup-definition code resource supports operations involving a custom dialog box that allows users to configure the telephone tool.
pascal long MyVSET (
         TELSetupPtr pSetup, short msg, long p1, long p2, long p3);
When this function is called, the msg parameter contains one of five messages, defined by constants:
enum {
   telSpreflightMsg        = 0,
   telSsetupMsg            = 1,
   telSitemMsg             = 2,
   telSfilterMsg           = 3,
   telScleanupMsg          = 4
};
These messages indicate that your tool should handle some part of the process of displaying a custom dialog box. The parameters p1, p2, and p3 have different meanings depending on which message is passed in the msg parameter. See "Setup-Definition Code Resource Messages" on page 6-41 for complete details.

Writing a Scripting Language Interface Code Resource
A scripting language interface code resource handles the communication between a scripting language and a telephone tool.
pascal long MyVSCR (TELHandle hTEL, short msg, long p1, long p2, long p3);
When this function is called, the msg parameter contains one of two messages, defined by constants:
enum {
   telMgetMsg              = 0,
   telMsetMsg              = 1
};
See "Scripting Language Interface Code Resource Messages" on page 6-43 for complete details on handling these messages.

Writing a Localization Code Resource
A localization code resource handles the localization of configuration strings related to a telephone tool. The entry point of the resource should be a function declared as follows:
pascal long MyVLOC (TELHandle hTEL, short msg, long p1, long p2, long p3);
When this function is called, the msg parameter contains one of two messages, defined by constants:
enum {
   telL2EnglishMsg         = 0,
   telL2IntlMsg            = 1
};
These messages indicate that your tool should localize a string either to English or to some other language. The parameters p1, p2, and p3 have different meanings depending on which message is passed in the msg parameter. See "Localization Code Resource Messages" on page 6-43 for complete details.

Sending Messages to the Telephone Manager
As you know, your telephone tool not only needs to respond to messages sent to it by the Telephone Manager, but it also needs to be able to send messages to the Telephone Manager. For example, when an application calls the TELOpenTerm function to open a telephone terminal associated with your tool, the Telephone Manager sends your tool the telOpenTermMsg message. Your tool should perform any operations necessary to make the specified terminal ready for use (for example, open any associated terminal drivers).
If successful, your tool should inform the Telephone Manager by sending back the telTermOpenMsg message and the telTermEnableMsg message. If unsuccessful, your tool should send back the telTermErrorMsg message. In virtually all cases, the Telephone Manager relays the messages your tool sends it to the appropriate application, which (in this case) can use those messages as indications that the terminal was successfully opened and initialized or that it could not be opened.
You send a message to the Telephone Manager by calling the appropriate master message handler of the Telephone Manager (a function defined by the Telephone Manager that receives and handles messages sent by telephone tools). The Telephone Manager maintains three master message handlers, one for each of the main types of messages your tool can send (that is, terminal messages, directory number messages, and call appearance messages). Before your tool can send a message to a master message handler, it must get the address of that master message handler from the Telephone Manager. The address of a master message handler is passed to your tool in a message. For instance, the Telephone Manager passes the address of its call appearance master message handler to your tool by sending it a message of type telCAMsgHandMsg. Each time the Telephone Manager sends your tool a telCAMsgHandMsg message, your tool should save the function pointer specified by parameter p1, as well as the event mask and globals pointer passed in parameters p1 and p3.
To send a message of a particular type, your tool should call the corresponding master message handler. Each master message handler requires a single parameter, which is always a pointer to a message-specific parameter block. For instance, when your tool sends the telCACallbackMsg message, the single parameter is a pointer to a call appearance generic message parameter block (page 6-63). The message descriptions (beginning on page 6-45) indicate which parameter blocks are required for which messages.